Skip to content

Writing Documentation

This page is intended as a quick reference to the Markdown syntax and the extensions available in the Abinit documentation. Markdown can be used almost everywhere: user-guide, tutorials, release notes, theory notes, the description of the input variables stored in python files inside abimkdocs as well as in the TEST_INFO section of the automatic tests.

As the original/official Markdown syntax rules state:

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

Basic Markdown syntax already covers most of our needs and the Abinit extensions (wiki links and Abinit plugins) facilitate the integration between the documentation on the website and the new developments done in the gilab branch. This page, for example, is entirely written in Markdown with the exception of the last two sections in which we discuss advanced features requiring some HTML code.

Markdown quick reference

Inline styles

Markdown Result Extension required
*italics* italics
**bold** bold
***bold and italic*** bold and italic
`monospace` monospace
~~strikethrough~~ strikethrough Tilde
CH~3~CH~2~OH CH3CH2OH Tilde
==highlight== highlight Mark
^^underline me^^ underline me Caret

As Markdown is not a “publishing format” providing a way to color text is out-of-scope for Markdown but it’s possible to use raw HTML code. For example, the following Markdown text:

Some Markdown text with <span style="color:red">some *red* text</span>.

produces: Some Markdown text with some red text.

For a more complete introduction to Markdown, please consult the Markdown Cheatsheet.

Code and syntax highlighting

Blocks of code are either fenced by lines with three back-ticks ``` or are indented with four spaces. For example, the Markdown text:

Fenced code has three back-ticks around it.


Fenced code has three back-ticks around it.

Alternatively, one can indent the code with four space such as in:

    abinit < tbase1_x.files 2> log &

that produces:

abinit < tbase1_x.files 2> log &

Fenced blocks is an alternative form that allows the specification of the language used for syntax highlighting. Fortran code, for example, can be included with:

do ii=1, 10
  write(*,*)"Hello world"
end do

that is displayed as:

do ii=1, 10
  write(*,*)"Hello world"
end do

To obtain inline highlighting, simply use back-ticks. As an example:

Inline `code` has `back-ticks` around it.


Inline code has back-ticks around it.


To create a table in Markdown use the syntax:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

that produces:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell


If the text inside the colum contains pipes (|), enclose it with back-ticks. or use a \ before the pipe.


To include figures, use the standard Markdown syntax:


For figures with a caption use the markdown-figures extension:

:   Convergenge of BSE optical spectrum wrt $\kk$-point sampling.
    See also [[ngkpt]] and [[shiftk]].

Convergenge of BSE optical spectrum wrt -point sampling. See also ngkpt and shiftk.

The caption can contain Latex equations as well as Abinit wiki links. <img> and <figure> elements are automatically centered via CSS directives declared in extra.css.

Pdf Files

Links to internal pdf files shipped with the Abinit documentation are inserted using the base name of the pdf file and the wikilink syntax:

    Please consult the [[pdf:howto_chebfi]] document.

that gives: Please consult the howto_chebfi.pdf document.


The .pdf extension at the end of the file is optional.

This is the recommended approach to link pdf documents in the description of the input variables. In the lessons and in the theory notes, on the other hand, you may want to to display the pdf file directly in the HTML page. In this case, use the HTML embed element:

<embed src="../howto_chebfi.pdf" type="application/pdf" width="100%" height="480px">`

See the automatically generated pdf gallery for examples.


Links to videos can be included with the standard Markdown syntax:

The video below gives an overwiew of the command line options of ``


that produces:

The video below gives an overwiew of the command line options of


More advanced features such as video galleries require a bit of HTML/CSS/JS code in the Markdown page. See for example the Abinit video gallery built with lightGallery.

The Markdown syntax for links is:

Markdown Result Extension required
[Links for videos](#videos) Links for videos
[About topics](abimkdocs#topics) About topics
[MBPT document](../theory/mbt) MBPT document
[The Abinit website]( The Abinit website

This is the recommended approach to create links to external resources, or internal links to other pages of the website, especially when there’s no shortcut is made available by the wikilink syntax. Links to external websites are signaled with the fontawesome icon: (see CSS rules in extra.css).

Note that linking to a page that is located in the same directory is trivial in Markdown. All the lessons, for example, are placed in the same directory (~doc/tutorial). To refer to the first PAW tutorial from the second tutorial, use:

[The first PAW tutorial](paw1)

There are however cases in which we would like to have an even simpler syntax to generate automatically links within our documentation, in particular links to:

  • The input variables declared in abinit_vars.yml.
  • The bibliographic citations declared in abiref.bib.
  • Input files or pseudopotentials used in the Abinit test suite.
  • Website pages commonly mentioned such as e.g. the topics page.

For this reason, we use the extentions API provided by python Markdown to extend the syntax of the parser, using the “Wikilink” syntax. Typical cases are discussed in the next sections.

The wikilink syntax is used with two pairs of square brackets and possible separators (:, # and |). In the simple case, this gives [ [name] ] although the more general form is

[ [namespace:name#section|text] ]

where namespace, section and text are optional (in such case, the adequate separator should not be mentioned). The namespace is not echoed in the Web page, while if a text is given, it will supercede the echo of the name in the Web page (see examples below).


Do not use parentheses within the pair of double brackets, the whole expression will not be recognized.

When an internal link is recognized, the dokuwiki string is replaced by the adequate HTML link There are a couple of names immediately recognized:

  • the name of an Abinit input variable e.g. “ecut” (provided it is mentioned in
  • the name of a bibliographical reference (provided it is mentioned in abiref.bib)
  • the path to a file in one of the ~abinit/tests/*/Input directory
  • the path to a reference output file in one of the ~abinit/tests/tuto*/Refs directories
  • the label of a section inside the own file


Markdown Result
[[ecut]] ecut
[[abinit:ecut]] ecut
[[anaddb:dipdip]] dipdip
[[dipdip@anaddb]] dipdip@anaddb
[[cite:Amadon2008]] [Amadon2008]
[[~abinit/tests/tutorial/Input/]] ~abinit/tests/tutorial/Input/
[[tests/tutorial/Input/]] tests/tutorial/Input/
[[test:libxc_41]] libxc[41]
[[tests/tutorial/Refs/tbase1_1.out]] tests/tutorial/Refs/tbase1_1.out
[[~abinit/tests/tutorial/Refs/tbase1_1.out]] ~abinit/tests/tutorial/Refs/tbase1_1.out
[[~abinit/tests/Psps_for_tests/6c.lda.atompaw]] ~abinit/tests/Psps_for_tests/6c.lda.atompaw
[[tests/Psps_for_tests/6c.lda.atompaw]] tests/Psps_for_tests/6c.lda.atompaw

The input variables for anaddb, optic and aim will be recognized if they are used with the namespaces anaddb, optic and aim. One has thus also the choice between the syntax [[anaddb:dipdip]] and [[dipdip@anaddb]]. In the first case, only dipdip is echoed, while in the second case, dipdip@anaddb is echoed. This syntax is needed because there’s also a dipdip variable in Abinit.

A wikilink that starts with # is interpreted as an internal link within the page hence

See [[#markdown-quick-reference|this section]] for more info

becomes: See this section for more info

although the same result can be obtained with the more readable Markdown syntax:

See [this section](#markdown-quick-reference) for more info

To specify the name of the anchor in a bibliographic citation use the syntax with the | separator:

Please consult [[cite:Gonze2016 | the last generic ABINIT article]].

that is rendered in HTML as: Please consult the last generic ABINIT article.


Please use the cite namespace. The syntax without namespace is deprecated and will be removed.

The script does a bit of formatting in these examples: it keeps one pair of square brackets in the case of a bibliographic reference, and add “~abinit/” in the case of a path. The syntax [[test:libxc_41]] is preferable when documenting new tests in the release notes. The python code issues a warning in the terminal if the link cannot be established.


Links to input files have a popover with the description of the test. Hovering on a citation opens a popover with the title reported in the Bibtex entry. Links to variables and internal files use a different font declared in extra.css.

Other internal links can be recognized thanks to the namespace.


Namespace Markdown Result
lesson [[lesson:gw1]] gw1 lesson
lesson [[lesson:index]] tutorial home page
topic [[topic:BSE]] topic_BSE
topic [[topic:index]] Topics index
help [[help:abinit]] abinit help file
help [[help:abinit#files-file]] abinit help file
theory [[theory:mbt]] mbt
varset [[varset:bse]] bse varset
cite [[cite:Amadon2008]] [Amadon2008]
ac [[]]
pdf [[pdf:howto_chebfi.pdf]] howto_chebfi.pdf
pdf [[pdf:howto_chebfi]] howto_chebfi.pdf
src [[src:94_scfcv/scfcv.F90]] 94_scfcv/scfcv.F90

#files-file is an HTML id defined in ~abinit/doc/guide/ with:

<a id="files-file"></a>
## 4 More detailed presentation of the files file


theorydoc and bib are deprecated and replaced by theory and cite, respectively.

Also in this case, it’s possible to specify the name of the link with the with the | separator so [[topic:PIMD#1|Introduction]] becomes Introduction.


Internal links are automatically generated by the Markdown parser as discussed in the Permalinks section.

Be careful when including a wikilink inside other square brackets e.g. [2+ [ [ecut] ] ]**2 as the occurrence of ]]] confuses the parser. The problem is easily solved by inserting whitespaces in the expression:

[ 2 + [[ecut]] ] ** 2

This version if much more readable and it also avoids possible problems with the ** that has a special meaning in Markdown.

To refer to a particular git commit inside a Markdown document use:

Solved in [[gitsha:f74dba1ed8346ca586dc95fd10fe4b8ced108d5e]]

that produces: f74dba1


This extension is useful to generate nice changelogs and release notes.

As for dokuwiki, some external links are also recognized. The following case are treated:

  • a link that starts with www.
  • the namespaces http, https, ftp, file
Markdown Result

It’s also possible to specify the name of the link with the | separator: [[|The ABINIT Wiki]] that gives The ABINIT Wiki

Permalinks are a feature of the Table of Contents extension, which is part of the standard Markdown library. The extension inserts an anchor at the end of each headline, which makes it possible to directly link to a subpart of the document.

By default, all headers will automatically have unique id attributes generated based upon the text of the header. The name of the anchor is constructed from the header by converting the string to lower-case ASCII, removing dots and other symbols such as & and replacing white spaces with a dash -. For instance, #wiki-links is the anchor associated to the “Wiki Links” section in this page and we can thus refer to it with the Markdown syntax:

As we have seen in the [previous section](#wiki-links)

that produces: As we have seen in the previous section


Hover with the mouse on the header in the HTML page to show the permalink in the browser. You can also copy the link and use the last part to generate the reference.


It is also possible to generate automatically the Table of Contents by just placing the [TOC] marker in the document where you would like the Table of Contents to appear. Then, a nested list of all the headers in the document will replace the marker. Note, however, that the use of [TOC] in our pages is not recomended as the Table of Contents is automatically generated by the Mkdocs theme and displayed in the navigation bar on the right.

Markdown extensions


SmartSymbols adds syntax for creating special characters such as trademarks, arrows, fractions, etc. The list of symbols supported by the extension is:

Markdown Result
(c) (c)
(r) (r)
c/o c/o
+/- ±
1/4, etc. ¼, etc.
1st 2nd etc. 1st 2nd etc.

Definition Lists

The Definition Lists extension adds the ability to create definition lists in Markdown documents. This extension is included in the standard Markdown library. The following text:

:   Pomaceous fruit of plants of the genus Malus in
    the family Rosaceae.

:   The fruit of an evergreen tree of the genus Citrus.

will be rendered as:

Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
The fruit of an evergreen tree of the genus Citrus.


Admonitions are useful to stress important sections (useful e.g. in the Abinit lessons). Admonition are created using the Markdown syntax:

!!! note
    Here is a note for you.


!!! danger "Don't try this at home!"
    Stand back. I'm about to try science!

for an admonition with a custom title (make sure to quote the title).

The types of admonitions available for use in MkDocs depend on the theme being used. The Material theme supports the following types:


I am a “note” admonition and look the same as “seealso”.


I am a “tip” admonition and look the same as “hint” and “important”.


I am a “warning” admonition and look the same as “attention” and “caution”.


I am a “danger” admonition and look the same as “error”.


I am a “summary” admonition and look the same as “tldr”.


I am a “success” admonition and look the same as “check” and “done”.


I am a “failure” admonition and look the same as “fail” and “missing”.


I am a “bug” admonition.

For the complete list, please consult the mkdocs-material documentation


Detail is an extension that creates collapsible elements that hide their content. It uses the HTML5 <details><summary> tags to accomplish this. It supports nesting and you can also force the default state to be open. This extension is used in the documentation of the input variable to generate a container with the list of tests associated to the variable but it can also be used for long FAQs of Q&A sections in the lessons.


???+ note "List of variables"
     [[ecut]] [[asr@anaddb]]

produces the open element:

List of variables

ecut asr@anaddb


??? note "Click to open!"
     [[ecut]] [[asr@anaddb]]

creates a closed element:

Click to open!

ecut asr@anaddb

Abinit extensions

To create a button that opens a dialog containing the input file, use:

    {% dialog tests/v1/Input/ %}

that produces:

If multiple files are used such as in:

{% dialog tests/v1/Input/ tests/v1/Input/ tests/v1/Input/ %}

a modal window with tabs is produced:

To create a button that opens a modal window containing the input file, use:

    {% modal tests/v1/Input/ %}

that produces:

This is useful for lessons to give direct access to the input files. If multiple files are used such as in:

    {% modal tests/v1/Input/ tests/v1/Input/ %}

a modal window with tabs is produced


Formulas written in LaTeX are interpreted automatically (at visualization time) thanks to the MathJax on-the-flight processor while the math extension for Python-Markdown is provided by python-markdown-math.

Latex equations can be used everywhere including the description of the variables reported in abinit_vars.yml and the description of the tests gives in the TEST_INFO section. For the Abinit documentation, the conventions are:

  • $...$ yields an onlinecite translation of the LaTeX formula.
  • $$...$$ yields display mode, the LaTeX formula being rendered on one dedicated line (moreover, centered).
  • To have the equations numbered, use the display mode above, and (inside the markers) declare your equation within the standard \begin{equation}...\end{equation} markers.
  • When a $ sign is inside a <pre>...</pre> HTML section, MathJax does not interpret it.
  • Use \$ to prevent a real \$ to be interpreted.

For instance $|\Phi\rangle$ produces while $$\Phi_\kq(\rr)$$ produces

Equations enclosed by $$...$$ or \begin{equation}...\end{equation} markers are automatically numbered and can be referenced inside the Markdown text using the standard Latex syntax:

G(12) = -i \langle \Theta^N_0|T\bigl[\Psi(1)\Psi^\dagger(2)\bigr]|\Theta^N_0 \rangle \label{eq:GreenDef}

that produces:

Equations can be referenced with:

The propagator in Eq.(\ref{eq:GreenDef})

that produces: The propagator in Eq.(\ref{eq:GreenDef})

Note that MathJax is configured with Latex macros to facilitate the insertion of symbols commonly used in our domain:

Markdown Result

Please consult the preamble in abinit_theme/main.html for the complete list of macros.


It seems that the plotly javascript library does not play well with MathJax as equations sometimes are not displayed when plotly is activated. This problem can be fixed by reloading the page. It should not represent a serious issue since plotly is used only in selected pages (like this one).


Unicode characters in particular Greek symbols and accented characters can be used in the documentation. The websites uses the Google’s Roboto font so Greek symbols can be included without using MathJax either by specifying the HTML entity or by copying the unicode character given in the two tables below. This could be useful if the page does not contain Latex equations and there are just a few Greek symbols to be inserted. Please do not use unicode characters in Latex equations.

Character Name Character Entity Hex Entity HTML Entity
GREEK CAPITAL LETTER ALPHA Α &‌#913; &‌#x0391 &‌Alpha;
GREEK CAPITAL LETTER BETA Β &‌#914; &‌#x0392 &‌Beta;
GREEK CAPITAL LETTER GAMMA Γ &‌#915; &‌#x0393 &‌Gamma;
GREEK CAPITAL LETTER DELTA Δ &‌#916; &‌#x0394 &‌Delta;
GREEK CAPITAL LETTER EPSILON Ε &‌#917; &‌#x0395 &‌Epsilon;
GREEK CAPITAL LETTER ZETA Ζ &‌#918; &‌#x0396 &‌Zeta;
GREEK CAPITAL LETTER ETA Η &‌#919; &‌#x0397 &‌Eta;
GREEK CAPITAL LETTER THETA Θ &‌#920; &‌#x0398 &‌Theta;
GREEK CAPITAL LETTER IOTA Ι &‌#921; &‌#x0399 &‌Iota;
GREEK CAPITAL LETTER KAPPA Κ &‌#922; &‌#x039A &‌Kappa;
GREEK CAPITAL LETTER LAM(B)DA Λ &‌#923; &‌#x039B &‌Lambda;
GREEK CAPITAL LETTER MU Μ &‌#924; &‌#x039C &‌Mu;
GREEK CAPITAL LETTER NU Ν &‌#925; &‌#x039D &‌Nu;
GREEK CAPITAL LETTER XI Ξ &‌#926; &‌#x039E &‌Xi;
GREEK CAPITAL LETTER OMICRON Ο &‌#927; &‌#x039F &‌Omicron;
GREEK CAPITAL LETTER PI Π &‌#928; &‌#x03A0 &‌Pi;
GREEK CAPITAL LETTER RHO Ρ &‌#929; &‌#x03A1 &‌Rho;
GREEK CAPITAL LETTER SIGMA Σ &‌#931; &‌#x03A3 &‌Sigma;
GREEK CAPITAL LETTER TAU Τ &‌#932; &‌#x03A4 &‌Tau;
GREEK CAPITAL LETTER UPSILON Υ &‌#933; &‌#x03A5 &‌Upsilon;
GREEK CAPITAL LETTER PHI Φ &‌#934; &‌#x03A6 &‌Phi;
GREEK CAPITAL LETTER CHI Χ &‌#935; &‌#x03A7 &‌Chi;
GREEK CAPITAL LETTER PSI Ψ &‌#936; &‌#x03A8 &‌Psi;
GREEK CAPITAL LETTER OMEGA Ω &‌#937; &‌#x03A9 &‌Omega;
Character Name Character Entity Hex Entity HTML Entity
GREEK SMALL LETTER ALPHA α &‌#945; &‌#x03B1 &‌alpha;
GREEK SMALL LETTER BETA β &‌#946; &‌#x03B2 &‌beta;
GREEK SMALL LETTER GAMMA γ &‌#947; &‌#x03B3 &‌gamma;
GREEK SMALL LETTER DELTA δ &‌#948; &‌#x03B4 &‌delta;
GREEK SMALL LETTER EPSILON ε &‌#949; &‌#x03B5 &‌epsilon;
GREEK SMALL LETTER ZETA ζ &‌#950; &‌#x03B6 &‌zeta;
GREEK SMALL LETTER ETA η &‌#951; &‌#x03B7 &‌eta;
GREEK SMALL LETTER THETA θ &‌#952; &‌#x03B8 &‌theta;
GREEK SMALL LETTER IOTA ι &‌#953; &‌#x03B9 &‌iota;
GREEK SMALL LETTER KAPPA κ &‌#954; &‌#x03BA &‌kappa;
GREEK SMALL LETTER LAM(B)DA λ &‌#955; &‌#x03BB &‌lambda;
GREEK SMALL LETTER MU μ &‌#956; &‌#x03BC &‌mu;
GREEK SMALL LETTER NU ν &‌#957; &‌#x03BD &‌nu;
GREEK SMALL LETTER XI ξ &‌#958; &‌#x03BE &‌xi;
GREEK SMALL LETTER OMICRON ο &‌#959; &‌#x03BF &‌omicron;
GREEK SMALL LETTER PI π &‌#960; &‌#x03C0 &‌pi;
GREEK SMALL LETTER RHO ρ &‌#961; &‌#x03C1 &‌rho;
GREEK SMALL LETTER SIGMA σ &‌#963; &‌#x03C3 &‌sigma;
GREEK SMALL LETTER TAU τ &‌#964; &‌#x03C4 &‌tau;
GREEK SMALL LETTER UPSILON υ &‌#965; &‌#x03C5 &‌upsilon;
GREEK SMALL LETTER PHI φ &‌#966; &‌#x03C6 &‌phi;
GREEK SMALL LETTER CHI χ &‌#967; &‌#x03C7 &‌chi;
GREEK SMALL LETTER PSI ψ &‌#968; &‌#x03C8 &‌psi;
GREEK SMALL LETTER OMEGA ω &‌#969; &‌#x03C9 &‌omega;

Taken from


plotly is a high-level, declarative charting library built on top of d3.js and plotly.js ships with over 20 chart types, including scientific charts, 3D graphs, statistical charts, SVG maps, financial charts, and more. Note that plotly is deactivated by default so you have to activate it inside the Markdown page by adding

plotly: true

to the front matter. This option will tell the browser to load the javascript library in the HTML page so that it’s possible to include HTML+javascript code to generate nice interactive plots inside the Markdown documentation. For example the HTML + javascript code:

<!-- Plots go in blank <div> elements.
     You can size them in the plot layout, or give the div a size as shown here.-->
<p>Here's a simple Plotly plot - <a href="">plotly.js documentation</a></p>

<div id="plotly_plot" style="width:90%;height:250px;"></div>
$(function() {
    Plotly.plot(document.getElementById('plotly_plot'), [{
        x: [1, 2, 3, 4, 5],
        y: [1, 2, 4, 8, 16] }],
        {margin: {t: 0}}

produces the following plot:

Here's a simple Plotly plot - plotly.js documentation

plotly is used to plot the code statistics but it’s not required for the proper functioning of the website.

Using HTML directly

HTML code can be used in Markdown but keep in mind that standard Markdown parsers will ignore text inside block-level HTML tags so

*Emphasized* text.

won’t work (but this situation only occurs if you are trying to write some advanced HTML code).

Another thing worth noticing is that Mkdocs (by default) generates a directory with an index.html file for every markdown page declared in mkdocs.yml (see also the official documentation). This means that a local webserver will serve this page at that can be equivalently reached from the more user friendly URL

This implementation detail does not affect links specified either with wikilink or markdown syntax because the python code will perform the automatic translation of the URLs. It does affect, however, the way you should specify src or href in HTML code because one should take into account the extra directory created by Mkdocs. In a nutshell, prepend a ../ to the relative path you would use inside the shell to specify the location of that resource with respect to the present page.

For instance, to build a Bootstrap carousel in this page using the images located in the ~abinit/doc/tutorial/bse_assets/ directory, one should use:

<div id="myCarousel" class="carousel slide" data-ride="carousel">
  <!-- Indicators -->
  <ol class="carousel-indicators">
    <li data-target="#myCarousel" data-slide-to="0" class="active"></li>
    <li data-target="#myCarousel" data-slide-to="1"></li>
  <!-- Wrapper for slides -->
  <div class="carousel-inner" role="listbox">
    <div class="item active">
      <img src="../../tutorial/bse_assets/tbs2_1.png" alt="Uncoverged BSE spectrum">
      <div class="carousel-caption">Unconverged BSE optical spectrum</div>
    <div class="item">
      <img src="../../tutorial/bse_assets/tbs5.png" alt="Converged BSE spectrum">
      <div class="carousel-caption">Convergenge of BSE optical spectrum wrt k-point sampling</div>

that produces:


Do not use root-relative URLs (e.g. /tutorial/bse_assets/tbs5.png) in HTML code because this will create problems when the site is deployed. Besides relative URLs allow us to serve multiple versions of the Abinit documentation associated to the different versions of the code.